<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>Mali OpenCL SDK v1.1.0: Template</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="logo.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">Mali OpenCL SDK v1.1.0
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.2 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Home</span></a></li>
      <li class="current"><a href="pages.html"><span>Help&#160;and&#160;Tutorials</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('template_tutorial.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Template </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>A skeleton file that can be used as a starting point for OpenCL development.</p>
<h1><a class="anchor" id="templateCheckList"></a>
Check-list</h1>
<p>Check-list for an OpenCL application:</p>
<ol type="1">
<li><a class="el" href="template_tutorial.html#templateEnvironment">Set up OpenCL environment</a></li>
<li><a class="el" href="template_tutorial.html#templateMemory">Set up memory/data</a></li>
<li><a class="el" href="template_tutorial.html#templateKernelExecution">Execute the kernel instances</a></li>
<li><a class="el" href="template_tutorial.html#templateAfterExecution">After execution</a></li>
</ol>
<h1><a class="anchor" id="templateWalkthrough"></a>
Walkthrough</h1>
<h2><a class="anchor" id="templateEnvironment"></a>
Set up OpenCL environment</h2>
<p><a class="el" href="template_8cpp.html">template.cpp</a> uses the <a class="el" href="common_8cpp.html">common.cpp</a> library to set up the environment.</p>
<ol type="1">
<li><p class="startli"><b>Create a context</b></p>
<p class="startli">Create an OpenCL context on the first available platform: </p>
<div class="fragment"><div class="line">    <span class="keywordflow">if</span> (!<a class="code" href="common_8cpp.html#a6fc67d121370b02ac8bff71ec00a7665" title="Create an OpenCL context on a GPU on the first available platform.">createContext</a>(&amp;context))</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="common_8cpp.html#acd459e74d0cef3c4616c7ce1a5a47f4d" title="Release any OpenCL objects that have been created.">cleanUpOpenCL</a>(context, commandQueue, program, kernel, memoryObjects, numMemoryObjects);</div>
<div class="line">        cerr &lt;&lt; <span class="stringliteral">&quot;Failed to create an OpenCL context. &quot;</span> &lt;&lt; __FILE__ &lt;&lt; <span class="stringliteral">&quot;:&quot;</span>&lt;&lt; __LINE__ &lt;&lt; endl;</div>
<div class="line">        <span class="keywordflow">return</span> 1;</div>
<div class="line">    }</div>
</div><!-- fragment --></li>
<li><p class="startli"><b>Create a command-queue</b></p>
<p class="startli">Create a command-queue to queue operations on the device: </p>
<div class="fragment"><div class="line">    <span class="keywordflow">if</span> (!<a class="code" href="common_8cpp.html#a30ee399cc6a4b82d46c581f037b447fa" title="Create an OpenCL command queue for a given context.">createCommandQueue</a>(context, &amp;commandQueue, &amp;device))</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="common_8cpp.html#acd459e74d0cef3c4616c7ce1a5a47f4d" title="Release any OpenCL objects that have been created.">cleanUpOpenCL</a>(context, commandQueue, program, kernel, memoryObjects, numMemoryObjects);</div>
<div class="line">        cerr &lt;&lt; <span class="stringliteral">&quot;Failed to create the OpenCL command queue. &quot;</span> &lt;&lt; __FILE__ &lt;&lt; <span class="stringliteral">&quot;:&quot;</span>&lt;&lt; __LINE__ &lt;&lt; endl;</div>
<div class="line">        <span class="keywordflow">return</span> 1;</div>
<div class="line">    }</div>
</div><!-- fragment --></li>
<li><p class="startli"><b>Create a program</b></p>
<p class="startli">Create an OpenCL program from a given file and compile it: </p>
<div class="fragment"><div class="line">    <span class="keywordflow">if</span> (!<a class="code" href="common_8cpp.html#a4feec45e4b990aad8e40cc3faa32a9c8">createProgram</a>(context, device, <span class="stringliteral">&quot;assets/template.cl&quot;</span>, &amp;program))</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="common_8cpp.html#acd459e74d0cef3c4616c7ce1a5a47f4d" title="Release any OpenCL objects that have been created.">cleanUpOpenCL</a>(context, commandQueue, program, kernel, memoryObjects, numMemoryObjects);</div>
<div class="line">        cerr &lt;&lt; <span class="stringliteral">&quot;Failed to create OpenCL program.&quot;</span> &lt;&lt; __FILE__ &lt;&lt; <span class="stringliteral">&quot;:&quot;</span>&lt;&lt; __LINE__ &lt;&lt; endl;</div>
<div class="line">        <span class="keywordflow">return</span> 1;</div>
<div class="line">    }</div>
</div><!-- fragment --></li>
<li><p class="startli"><b>Create a kernel</b></p>
<p class="startli">Create a kernel object for the kernel function <a class="el" href="template_8cl.html#a3fd9dfc155a2b110d8632041d0961625" title="Template empty kernel.">template()</a>: </p>
<div class="fragment"><div class="line">    kernel = clCreateKernel(program, <span class="stringliteral">&quot;template&quot;</span>, &amp;errorNumber);</div>
<div class="line">    <span class="keywordflow">if</span> (!<a class="code" href="common_8cpp.html#a73727ed6f5d821d8c97756404e145644" title="Check an OpenCL error number for errors.">checkSuccess</a>(errorNumber))</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="common_8cpp.html#acd459e74d0cef3c4616c7ce1a5a47f4d" title="Release any OpenCL objects that have been created.">cleanUpOpenCL</a>(context, commandQueue, program, kernel, memoryObjects, numMemoryObjects);</div>
<div class="line">        cerr &lt;&lt; <span class="stringliteral">&quot;Failed to create OpenCL kernel. &quot;</span> &lt;&lt; __FILE__ &lt;&lt; <span class="stringliteral">&quot;:&quot;</span>&lt;&lt; __LINE__ &lt;&lt; endl;</div>
<div class="line">        <span class="keywordflow">return</span> 1;</div>
<div class="line">    }</div>
</div><!-- fragment --> </li>
</ol>
<h2><a class="anchor" id="templateMemory"></a>
Set up memory/data</h2>
<ol type="1">
<li><p class="startli"><b>Create memory buffers</b></p>
<p class="startli">Request memory buffers for any data that you need to access from the device. For more information have a look at the <a class="el" href="hello_world_tutorial.html">Hello World</a>.</p>
</li>
<li><p class="startli"><b>Initialise the input data</b></p>
<p class="startli">If you need to initialise the data from the CPU side, then you need to:</p>
<ol type="a">
<li>Map the buffer to a local pointer</li>
<li>Initialise the data using the mapped pointer</li>
<li>Un-map the data</li>
</ol>
<p class="startli">For more information have a look at the <a class="el" href="hello_world_tutorial.html">Hello World</a> tutorial.</p>
</li>
<li><p class="startli"><b>Set up kernel arguments</b></p>
<p class="startli">Pass the memory buffers and/or other variables to the kernel as arguments.</p>
<p class="startli">For more information have a look at the <a class="el" href="hello_world_tutorial.html">Hello World</a> tutorial.</p>
</li>
</ol>
<h2><a class="anchor" id="templateKernelExecution"></a>
Execute the kernel instances</h2>
<ol type="1">
<li><p class="startli"><b>Define the number of kernel instances</b></p>
<p class="startli">The <code>globalWorkSize</code> determines how many kernel instances are run.</p>
<div class="fragment"><div class="line">    <span class="keyword">const</span> <span class="keywordtype">int</span> workDimensions = 1;</div>
<div class="line">    <span class="keywordtype">size_t</span> globalWorkSize[workDimensions] = {1};</div>
</div><!-- fragment --><p> For another example have a look at the <a class="el" href="hello_world_tutorial.html">Hello World</a> tutorial or any of the other tutorials.</p>
</li>
<li><p class="startli"><b>Enqueue the kernel</b></p>
<p class="startli">Enqueue the kernel for execution. To retrieve profiling information, we define a <code>cl_event</code> and pass it to <code>clEnqueueNDRangeKernel()</code>.</p>
<div class="fragment"><div class="line">    <span class="comment">/* An event to associate with the kernel. Allows us to retrieve profiling information later. */</span></div>
<div class="line">    cl_event <span class="keyword">event</span> = 0;</div>
<div class="line"></div>
<div class="line">    <span class="keywordflow">if</span> (!<a class="code" href="common_8cpp.html#a73727ed6f5d821d8c97756404e145644" title="Check an OpenCL error number for errors.">checkSuccess</a>(clEnqueueNDRangeKernel(commandQueue, kernel, workDimensions, NULL, globalWorkSize, NULL, 0, NULL, &amp;event)))</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="common_8cpp.html#acd459e74d0cef3c4616c7ce1a5a47f4d" title="Release any OpenCL objects that have been created.">cleanUpOpenCL</a>(context, commandQueue, program, kernel, memoryObjects, numMemoryObjects);</div>
<div class="line">        cerr &lt;&lt; <span class="stringliteral">&quot;Failed enqueuing the kernel. &quot;</span> &lt;&lt; __FILE__ &lt;&lt; <span class="stringliteral">&quot;:&quot;</span>&lt;&lt; __LINE__ &lt;&lt; endl;</div>
<div class="line">        <span class="keywordflow">return</span> 1;</div>
<div class="line">    }</div>
</div><!-- fragment --></li>
<li><p class="startli"><b>Wait for kernel execution</b></p>
<p class="startli">Wait until all the kernel instances have finished executing: </p>
<div class="fragment"><div class="line">    <span class="keywordflow">if</span> (!<a class="code" href="common_8cpp.html#a73727ed6f5d821d8c97756404e145644" title="Check an OpenCL error number for errors.">checkSuccess</a>(clFinish(commandQueue)))</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="common_8cpp.html#acd459e74d0cef3c4616c7ce1a5a47f4d" title="Release any OpenCL objects that have been created.">cleanUpOpenCL</a>(context, commandQueue, program, kernel, memoryObjects, numMemoryObjects);</div>
<div class="line">        cerr &lt;&lt; <span class="stringliteral">&quot;Failed waiting for kernel execution to finish. &quot;</span> &lt;&lt; __FILE__ &lt;&lt; <span class="stringliteral">&quot;:&quot;</span>&lt;&lt; __LINE__ &lt;&lt; endl;</div>
<div class="line">        <span class="keywordflow">return</span> 1;</div>
<div class="line">    }</div>
</div><!-- fragment --><p> <b>Note:</b> This may not be required depending on the application.</p>
</li>
</ol>
<h2><a class="anchor" id="templateAfterExecution"></a>
After execution</h2>
<ol type="1">
<li><p class="startli"><b>Print profiling information</b></p>
<p class="startli">Print the profiling information for the event (queueing, waiting and running time): </p>
<div class="fragment"><div class="line">    <a class="code" href="common_8cpp.html#a33ff0013574626bb47147495e02b5d08" title="Print the profiling information associated with an OpenCL event.">printProfilingInfo</a>(event);</div>
<div class="line">    <span class="comment">/* Release the event object. */</span></div>
<div class="line">    <span class="keywordflow">if</span> (!<a class="code" href="common_8cpp.html#a73727ed6f5d821d8c97756404e145644" title="Check an OpenCL error number for errors.">checkSuccess</a>(clReleaseEvent(event)))</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="common_8cpp.html#acd459e74d0cef3c4616c7ce1a5a47f4d" title="Release any OpenCL objects that have been created.">cleanUpOpenCL</a>(context, commandQueue, program, kernel, memoryObjects, numMemoryObjects);</div>
<div class="line">        cerr &lt;&lt; <span class="stringliteral">&quot;Failed releasing the event object. &quot;</span> &lt;&lt; __FILE__ &lt;&lt; <span class="stringliteral">&quot;:&quot;</span>&lt;&lt; __LINE__ &lt;&lt; endl;</div>
<div class="line">        <span class="keywordflow">return</span> 1;</div>
<div class="line">    }</div>
</div><!-- fragment --></li>
<li><p class="startli"><b>Retrieve results</b></p>
<p class="startli">To access the results from the CPU side, you need to:</p>
<ol type="a">
<li>Map the output buffer to a local pointer</li>
<li>Read the results using the mapped pointer</li>
<li>Un-map the data</li>
</ol>
<p class="startli">For more information have a look at the <a class="el" href="hello_world_tutorial.html">Hello World</a> tutorial.</p>
</li>
<li><p class="startli"><b>Release OpenCL objects</b></p>
<p class="startli">Release any OpenCL objects that have been created.</p>
<div class="fragment"><div class="line">    <a class="code" href="common_8cpp.html#acd459e74d0cef3c4616c7ce1a5a47f4d" title="Release any OpenCL objects that have been created.">cleanUpOpenCL</a>(context, commandQueue, program, kernel, memoryObjects, numMemoryObjects);</div>
</div><!-- fragment --> </li>
</ol>
<h1><a class="anchor" id="templateRunning"></a>
Running the Sample</h1>
<p>This sample does nothing apart from printing profiling information.</p>
<ol type="1">
<li><p class="startli">From a command prompt in the root of the SDK, run:</p>
<div class="fragment"><div class="line">cd samples/<span class="keyword">template</span></div>
</div><!-- fragment --> <div class="fragment"><div class="line">make install</div>
</div><!-- fragment --><p class="startli">This compiles the template sample code and copies all the files it needs to run to the bin folder in the root directory of the SDK.</p>
</li>
<li>Copy this folder to the board.</li>
<li><p class="startli">Navigate to the folder on the board and run the template binary:</p>
<div class="fragment"><div class="line">./<span class="keyword">template</span></div>
</div><!-- fragment --></li>
<li><p class="startli">You should see output similar to:</p>
<div class="fragment"><div class="line">Profiling information:</div>
<div class="line">Queued time:    0.062ms</div>
<div class="line">Wait time:      0.071535ms</div>
<div class="line">Run time:       0.001398ms</div>
</div><!-- fragment --></li>
</ol>
<p>Find solutions for <a class="el" href="common_issues.html">Common Issues</a>.</p>
<h1><a class="anchor" id="templateMoreInformation"></a>
More Information</h1>
<p>For more information have a look at the code in <a class="el" href="template_8cpp.html">template.cpp</a> and <a class="el" href="template_8cl.html">template.cl</a>. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="tutorials.html">Tutorials</a></li>
    <li class="footer">
        <a href="http://www.arm.com/">(C) ARM Ltd. 2013</a>
    </li>
  </ul>
</div>
</body>
</html>
